﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
<title>A guide to the Breadcrumb Trail plugin</title>

<link rel="stylesheet" href="readme.css" type="text/css" media="screen" />

</head>
<body>

<h1>A guide to Breadcrumb Trail</h1>

<p class="first"><em>Breadcrumb Trail</em> is a plugin that displays a breadcrumb menu on your site.  Plain and simple.</p>

<p class="second">How is it any better than any other breadcrumb plugin?  Well, it's probably not, to be perfectly honest.  This is just a script I've been building upon for several years that I usually include with my WordPress themes.  I figured I'd package it as a plugin for others to use as well.</p>

<h2>How to install the plugin</h2>

<ol>
<li>Uzip the <code>breadcrumb-trail.zip</code> folder.</li>
<li>Upload the <code>breadcrumb-trail</code> folder to your <code>/wp-content/plugins</code> directory.</li>
<li>In your WordPress dashboard, head over to the <em>Plugins</em> section.</li>
<li>Activate <em>Breadcrumb Trail</em>.</li>
</ol>

<h2>How to use the plugin</h2>

<p>This plugin won't work automatically because there's no way for me to know where it should show within your theme.  So, you'll have to add it manually in your template files.  <em>Where?</em> Well, that's really up to you.  You can add it pretty much anywhere you want.</p>

<p>This is the basic code:</p>

<pre><code>&lt;?php breadcrumb_trail(); ?></code></pre>

<h2>The default parameters</h2>

<p>By default, this plugin is designed to show things a certain way.  Here are the defaults:</p>

<pre><code>$defaults = array(
	'separator' => '/',
	'before' => '&lt;span class="breadcrumb-title">' . __('Browse:', 'breadcrumb_trail') . '&lt;/span>',
	'after' => false,
	'front_page' => true,
	'show_home' => __('Home', 'breadcrumb_trail'),
	'singular_{$post_type}_taxonomy' => false,
	'echo' => true,
);</code></pre>

<dl>
	<dt>separator</dt>
	<dd>The element that separates each item in the breadcrumb menu.</dd>
	<dt>before</dt>
	<dd>What should be shown before the trail.</dd>
	<dt>after</dt>
	<dd>What should be shown after the trail.</dd>
	<dt>show_home</dt>
	<dd>The text for the home link.  Set to <code>false</code> if no home link is needed.</dd>
	<dt>singular_{$post_type}_taxonomy</dt>
	<dd>A taxonomy to use as part of the leading trail on singular views of specific post types.</dd>
	<dt>echo</dt>
	<dd>Whether to print on the screen or return for use in a function.</dd>
</dl>

<h2>Custom examples</h2>

<p>Let's change the text before the breadcrumb trail.</p>

<pre><code>&lt;?php breadcrumb_trail( array( 'before' => 'You are here &amp;raquo;' ) ); ?></code></pre>

<p>How about we change the separator between each item?</p>

<pre><code>&lt;?php breadcrumb_trail( array( 'separator' => '&amp;rarr;' ) ); ?></code></pre>

<p>This time, we'll wrap the entire menu in brackets.</p>

<pre><code>&lt;?php breadcrumb_trail( array( 'before' => '{', 'after' => '}' ) ); ?></code></pre>

<p>Now, let's add post tags as part of the trail for singular posts.</p>

<pre><code>&lt;?php breadcrumb_trail( array( 'singular_post_taxonomy' => 'post_tag' ) ); ?></code></pre>

<p>Pretty simple stuff, right?  Just mix and match the parameters however you want.</p>

<h2>Protect yourself from errors in the future</h2>

<p>
Sometimes, we stop using plugins, but we forget to remove the function calls to the plugins in our theme files.  When deactivated, this causes errors.  To protect yourself from these errors, you can call the breadcrumb trail like this:
</p>

<pre><code>&lt;?php if ( function_exists( 'breadcrumb_trail' ) ) { breadcrumb_trail(); } ?></code></pre>

<p>
Basically, this just checks to see if the plugin is activated and has loaded the appropriate function.
</p>

<h2>Styling your breadcrumb trail</h2>

<p>
<em>Breadcrumb Trail</em> comes with some extra classes to work with, so you can have a bit of freedom when styling your menu.  Here are the <acronym title="Cascading Style Sheets">CSS</acronym> classes for your use:
</p>

<pre><code>.breadcrumb {
	/* This is the outer 'div' you can style */
	}

.breadcrumb-trail {
	/* This is the inner 'div' you can style */
	}</code></pre>

<h2>Developer tools</h2>

<p>If you're a theme developer, you can always add checks for this plugin and place it yourself within your template files or use <code>add_action()</code> to add it to a custom theme hook.</p>

<p>This plugin has three filter hooks for use as well:</p>

<dl>
	<dt>breadcrumb_trail_args</dt>
	<dd>Overwrite the arguments input and/or the defaults.</dd>
	<dt>breadcrumb_trail</dt>
	<dd>Completely overwrite the entire breadcrumb menu.</dd>
	<dt>breadcrumb_trail_items</dt>
	<dd>Overwrite or extend the rrray of items shown in the trail.</dd>
</dl>

<h2>Plugin support</h2>

<p>I run a WordPress community called <a href="http://themehybrid.com" title="Theme Hybrid">Theme Hybrid</a>, which is where I fully support all of my WordPress projects, including plugins.  You can sign up for an account to get plugin support for a small yearly fee ($25 <acronym title="United States Dollars">USD</acronym> at the time of writing).</p>

<p>I know.  I know.  You might not want to pay for support, but just consider it a donation to the project.  To continue making cool, <acronym title="GNU General Public License">GPL</acronym>-licensed plugins and having the time to support them, I must pay the bills.</p>

<h2>Copyright &amp; license</h2>

<p><em>Breadcrumb Trail</em> is licensed under the <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html" title="GNU GPL">GNU General Public License</a>, version 2 (<acronym title="GNU General Public License">GPL</acronym>).</p>

<p>This plugin is copyrighted to <a href="http://justintadlock.com" title="Justin Tadlock">Justin Tadlock</a>.</p>

<p>2008&thinsp;&ndash;&thinsp;2011 &copy; Justin Tadlock.  All rights reserved.</p>

</body>
</html>